Source code: org/osgi/service/wireadmin/Wire.java
1 /*
2 * $Header: /cvshome/repository/org/osgi/service/wireadmin/Wire.java,v 1.13 2002/10/08 06:43:04 pkriens Exp $
3 *
4 * Copyright (c) The Open Services Gateway Initiative (2002).
5 * All Rights Reserved.
6 *
7 * Implementation of certain elements of the Open Services Gateway Initiative
8 * (OSGI) Specification may be subject to third party intellectual property
9 * rights, including without limitation, patent rights (such a third party may
10 * or may not be a member of OSGi). OSGi is not responsible and shall not be
11 * held responsible in any manner for identifying or failing to identify any or
12 * all such third party intellectual property rights.
13 *
14 * This document and the information contained herein are provided on an "AS
15 * IS" basis and OSGI DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
16 * BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL
17 * NOT INFRINGE ANY RIGHTS AND ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR
18 * FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT WILL OSGI BE LIABLE FOR ANY
19 * LOSS OF PROFITS, LOSS OF BUSINESS, LOSS OF USE OF DATA, INTERRUPTION OF
20 * BUSINESS, OR FOR DIRECT, INDIRECT, SPECIAL OR EXEMPLARY, INCIDENTIAL,
21 * PUNITIVE OR CONSEQUENTIAL DAMAGES OF ANY KIND IN CONNECTION WITH THIS
22 * DOCUMENT OR THE INFORMATION CONTAINED HEREIN, EVEN IF ADVISED OF THE
23 * POSSIBILITY OF SUCH LOSS OR DAMAGE.
24 *
25 * All Company, brand and product names may be trademarks that are the sole
26 * property of their respective owners. All rights reserved.
27 */
28
29 package org.osgi.service.wireadmin;
30
31 import java.util.Dictionary;
32
33 /**
34 * A connection between a Producer service and a Consumer service.
35 *
36 * <p>A <tt>Wire</tt> object connects a Producer service
37 * to a Consumer service.
38 * Both the Producer and Consumer services are identified
39 * by their unique <tt>service.pid</tt> values.
40 * The Producer and Consumer services may communicate with
41 * each other via <tt>Wire</tt> objects that connect them.
42 * The Producer service may send updated values to the
43 * Consumer service by calling the {@link #update} method.
44 * The Consumer service may request an updated value from the
45 * Producer service by calling the {@link #poll} method.
46 *
47 * <p>A Producer service and a Consumer service may be
48 * connected through multiple <tt>Wire</tt> objects.
49 *
50 * <p>Security Considerations. <tt>Wire</tt> objects are available to
51 * Producer and Consumer services connected to a given
52 * <tt>Wire</tt> object and to bundles which can access the <tt>WireAdmin</tt> service.
53 * A bundle must have <tt>ServicePermission[GET,WireAdmin]</tt> to get the <tt>WireAdmin</tt> service to
54 * access all <tt>Wire</tt> objects.
55 * A bundle registering a Producer service or a Consumer service
56 * must have the appropriate <tt>ServicePermission[REGISTER,Consumer|Producer]</tt> to register the service and
57 * will be passed <tt>Wire</tt> objects when the service object's
58 * <tt>consumersConnected</tt> or <tt>producersConnected</tt> method is called.
59 *
60 * <p>Scope. Each Wire object can have a scope set with the <tt>setScope</tt> method. This
61 * method should be called by a Consumer service when it assumes a Producer service that is
62 * composite (supports multiple information items). The names in the scope must be
63 * verified by the <tt>Wire</tt> object before it is used in communication. The semantics of the
64 * names depend on the Producer service and must not be interpreted by the Wire Admin service.
65 *
66 * @version $Revision: 1.13 $
67 * @author Open Services Gateway Initiative
68 */
69 public interface Wire
70 {
71 /**
72 * Return the state of this <tt>Wire</tt> object.
73 *
74 * <p>A connected <tt>Wire</tt> must always be disconnected before
75 * becoming invalid.
76 *
77 * @return <tt>false</tt> if this <tt>Wire</tt> object is invalid because it
78 * has been deleted via {@link WireAdmin#deleteWire};
79 * <tt>true</tt> otherwise.
80 */
81 public boolean isValid();
82
83 /**
84 * Return the connection state of this <tt>Wire</tt> object.
85 *
86 * <p>A <tt>Wire</tt> is connected after the Wire Admin service receives
87 * notification that the Producer service and
88 * the Consumer service for this <tt>Wire</tt> object are both registered.
89 * This method will return <tt>true</tt> prior to notifying the Producer
90 * and Consumer services via calls
91 * to their respective <tt>consumersConnected</tt> and <tt>producersConnected</tt>
92 * methods.
93 * <p>A <tt>WireAdminEvent</tt> of type {@link WireAdminEvent#WIRE_CONNECTED}
94 * must be broadcast by the Wire Admin service when
95 * the <tt>Wire</tt> becomes connected.
96 *
97 * <p>A <tt>Wire</tt> object
98 * is disconnected when either the Consumer or Producer
99 * service is unregistered or the <tt>Wire</tt> object is deleted.
100 * <p>A <tt>WireAdminEvent</tt> of type {@link WireAdminEvent#WIRE_DISCONNECTED}
101 * must be broadcast by the Wire Admin service when
102 * the <tt>Wire</tt> becomes disconnected.
103 *
104 * @return <tt>true</tt> if both the Producer and Consumer
105 * for this <tt>Wire</tt> object are connected to the <tt>Wire</tt> object;
106 * <tt>false</tt> otherwise.
107 */
108 public boolean isConnected();
109
110 /**
111 * Return the list of data types understood by the
112 * Consumer service connected to this <tt>Wire</tt> object. Note that
113 * subclasses of the classes in this list are acceptable data types as well.
114 *
115 * <p>The list is the value of the {@link WireConstants#WIREADMIN_CONSUMER_FLAVORS}
116 * service property of the
117 * Consumer service object connected to this object. If no such
118 * property was registered or the type of the property value is not
119 * <tt>Class[]</tt>, this method must return <tt>null</tt>.
120 *
121 * @return An array containing the list of classes understood by the
122 * Consumer service or <tt>null</tt> if
123 * the <tt>Wire</tt> is not connected,
124 * or the consumer did not register a {@link WireConstants#WIREADMIN_CONSUMER_FLAVORS} property
125 * or the value of the property is not of type <tt>Class[]</tt>.
126 */
127 public Class[] getFlavors();
128
129 /**
130 * Update the value.
131 *
132 * <p>This methods is called by the Producer service to
133 * notify the Consumer service connected to this <tt>Wire</tt> object
134 * of an updated value.
135 * <p>If the properties of this <tt>Wire</tt> object contain a
136 * {@link WireConstants#WIREADMIN_FILTER} property,
137 * then filtering is performed.
138 * If the Producer service connected to this <tt>Wire</tt>
139 * object was registered with the service
140 * property {@link WireConstants#WIREADMIN_PRODUCER_FILTERS}, the
141 * Producer service will perform the filtering according to the rules specified
142 * for the filter. Otherwise, this <tt>Wire</tt> object
143 * will perform the filtering of the value.
144 * <p>If no filtering is done, or the filter indicates the updated value should
145 * be delivered to the Consumer service, then
146 * this <tt>Wire</tt> object must call
147 * the {@link Consumer#updated} method with the updated value.
148 * If this <tt>Wire</tt> object is not connected, then the Consumer
149 * service must not be called and the value is ignored.<p>
150 * If the value is an <tt>Envelope</tt> object, and the scope name is not permitted, then the
151 * <tt>Wire</tt> object must ignore this call and not transfer the object to the Consumer
152 * service.
153 *
154 * <p>A <tt>WireAdminEvent</tt> of type {@link WireAdminEvent#WIRE_TRACE}
155 * must be broadcast by the Wire Admin service after
156 * the Consumer service has been successfully called.
157 *
158 * @param value The updated value. The value should be an instance of
159 * one of the types returned by {@link #getFlavors}.
160 * @see WireConstants#WIREADMIN_FILTER
161 */
162 public void update(Object value);
163
164 /**
165 * Poll for an updated value.
166 *
167 * <p>This methods is normally called by the Consumer service to
168 * request an updated value from the Producer service
169 * connected to this <tt>Wire</tt> object.
170 * This <tt>Wire</tt> object will call
171 * the {@link Producer#polled} method to obtain an updated value.
172 * If this <tt>Wire</tt> object is not connected, then the Producer
173 * service must not be called.<p>
174 *
175 * If this <tt>Wire</tt> object has a scope, then this method
176 * must return an array of <tt>Envelope</tt> objects. The objects returned must
177 * match the scope of this object. The <tt>Wire</tt> object must remove
178 * all <tt>Envelope</tt> objects with a scope name that is not in the <tt>Wire</tt> object's scope.
179 * Thus, the list of objects returned
180 * must only contain <tt>Envelope</tt> objects with a permitted scope name. If the
181 * array becomes empty, <tt>null</tt> must be returned.
182 *
183 * <p>A <tt>WireAdminEvent</tt> of type {@link WireAdminEvent#WIRE_TRACE}
184 * must be broadcast by the Wire Admin service after
185 * the Producer service has been successfully called.
186 *
187 * @return A value whose type should be one of the types
188 * returned by {@link #getFlavors}, <tt>Envelope[]</tt>, or <tt>null</tt> if
189 * the <tt>Wire</tt> object is not connected,
190 * the Producer service threw an exception, or
191 * the Producer service returned a value which is not an instance of
192 * one of the types returned by {@link #getFlavors}.
193 */
194 public Object poll();
195
196 /**
197 * Return the last value sent through this <tt>Wire</tt> object.
198 *
199 * <p>The returned value is the most recent, valid value passed to the
200 * {@link #update} method or returned by the {@link #poll} method
201 * of this object. If filtering is performed by this <tt>Wire</tt> object,
202 * this methods returns the last value provided by the Producer service. This
203 * value may be an <tt>Envelope[]</tt> when the Producer service
204 * uses scoping. If the return value is an Envelope object (or array), it
205 * must be verified that the Consumer service has the proper WirePermission to see it.
206 *
207 * @return The last value passed though this <tt>Wire</tt> object
208 * or <tt>null</tt> if no valid values have been passed or the Consumer service has no permission.
209 */
210 public Object getLastValue();
211
212 /**
213 * Return the wire properties for this <tt>Wire</tt> object.
214 *
215 * @return The properties for this <tt>Wire</tt> object.
216 * The returned <tt>Dictionary</tt> must be read only.
217 */
218 public Dictionary getProperties();
219
220
221 /**
222 * Return the calculated scope of this <tt>Wire</tt> object.
223 *
224 * The purpose of the <tt>Wire</tt> object's scope is to allow a Producer
225 * and/or Consumer service to produce/consume different types
226 * over a single <tt>Wire</tt> object (this was deemed necessary for efficiency
227 * reasons). Both the Consumer service and the
228 * Producer service must set an array of scope names (their scope) with
229 * the service registration property <tt>WIREADMIN_PRODUCER_SCOPE</tt>, or <tt>WIREADMIN_CONSUMER_SCOPE</tt> when they can
230 * produce multiple types. If a Producer service can produce different types, it should set this property
231 * to the array of scope names it can produce, the Consumer service
232 * must set the array of scope names it can consume. The scope of a <tt>Wire</tt>
233 * object is defined as the intersection of permitted scope names of the
234 * Producer service and Consumer service.
235 * <p>If neither the Consumer, or the Producer service registers scope names with its
236 * service registration, then the <tt>Wire</tt> object's scope must be <tt>null</tt>.
237 * <p>The <tt>Wire</tt> object's scope must not change when a Producer or Consumer services
238 * modifies its scope.
239 * <p>A scope name is permitted for a Producer service when the registering bundle has
240 * <tt>WirePermission[PRODUCE]</tt>, and for a Consumer service when
241 * the registering bundle has <tt>WirePermission[CONSUME]</tt>.<p>
242 * If either Consumer service or Producer service has not set a <tt>WIREADMIN_*_SCOPE</tt> property, then
243 * the returned value must be <tt>null</tt>.<p>
244 * If the scope is set, the <tt>Wire</tt> object must enforce the scope names when <tt>Envelope</tt> objects are
245 * used as a parameter to update or returned from the <tt>poll</tt> method. The <tt>Wire</tt> object must then
246 * remove all <tt>Envelope</tt> objects with a scope name that is not permitted.
247 *
248 * @return A list of permitted scope names or null if the Produce or Consumer service has set no scope names.
249 */
250 public String [] getScope();
251
252
253 /**
254 * Return true if the given name is in this <tt>Wire</tt> object's scope.
255 *
256 * @param name The scope name
257 * @return true if the name is listed in the permitted scope names
258 */
259 public boolean hasScope( String name );
260 }
261