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 import java.util.Dictionary;
019
020 /**
021 * A connection between a Producer service and a Consumer service.
022 *
023 * <p>
024 * A <code>Wire</code> object connects a Producer service to a Consumer service.
025 * Both the Producer and Consumer services are identified by their unique
026 * <code>service.pid</code> values. The Producer and Consumer services may
027 * communicate with each other via <code>Wire</code> objects that connect them.
028 * The Producer service may send updated values to the Consumer service by
029 * calling the {@link #update} method. The Consumer service may request an
030 * updated value from the Producer service by calling the {@link #poll} method.
031 *
032 * <p>
033 * A Producer service and a Consumer service may be connected through multiple
034 * <code>Wire</code> objects.
035 *
036 * <p>
037 * Security Considerations. <code>Wire</code> objects are available to Producer
038 * and Consumer services connected to a given <code>Wire</code> object and to
039 * bundles which can access the <code>WireAdmin</code> service. A bundle must have
040 * <code>ServicePermission[WireAdmin,GET]</code> to get the <code>WireAdmin</code>
041 * service to access all <code>Wire</code> objects. A bundle registering a
042 * Producer service or a Consumer service must have the appropriate
043 * <code>ServicePermission[Consumer|Producer,REGISTER]</code> to register the
044 * service and will be passed <code>Wire</code> objects when the service object's
045 * <code>consumersConnected</code> or <code>producersConnected</code> method is
046 * called.
047 *
048 * <p>
049 * Scope. Each Wire object can have a scope set with the <code>setScope</code>
050 * method. This method should be called by a Consumer service when it assumes a
051 * Producer service that is composite (supports multiple information items). The
052 * names in the scope must be verified by the <code>Wire</code> object before it
053 * is used in communication. The semantics of the names depend on the Producer
054 * service and must not be interpreted by the Wire Admin service.
055 *
056 * @version $Revision: 5673 $
057 */
058 public interface Wire {
059 /**
060 * Return the state of this <code>Wire</code> object.
061 *
062 * <p>
063 * A connected <code>Wire</code> must always be disconnected before becoming
064 * invalid.
065 *
066 * @return <code>false</code> if this <code>Wire</code> object is invalid
067 * because it has been deleted via {@link WireAdmin#deleteWire};
068 * <code>true</code> otherwise.
069 */
070 public boolean isValid();
071
072 /**
073 * Return the connection state of this <code>Wire</code> object.
074 *
075 * <p>
076 * A <code>Wire</code> is connected after the Wire Admin service receives
077 * notification that the Producer service and the Consumer service for this
078 * <code>Wire</code> object are both registered. This method will return
079 * <code>true</code> prior to notifying the Producer and Consumer services via
080 * calls to their respective <code>consumersConnected</code> and
081 * <code>producersConnected</code> methods.
082 * <p>
083 * A <code>WireAdminEvent</code> of type {@link WireAdminEvent#WIRE_CONNECTED}
084 * must be broadcast by the Wire Admin service when the <code>Wire</code>
085 * becomes connected.
086 *
087 * <p>
088 * A <code>Wire</code> object is disconnected when either the Consumer or
089 * Producer service is unregistered or the <code>Wire</code> object is
090 * deleted.
091 * <p>
092 * A <code>WireAdminEvent</code> of type
093 * {@link WireAdminEvent#WIRE_DISCONNECTED} must be broadcast by the Wire
094 * Admin service when the <code>Wire</code> becomes disconnected.
095 *
096 * @return <code>true</code> if both the Producer and Consumer for this
097 * <code>Wire</code> object are connected to the <code>Wire</code>
098 * object; <code>false</code> otherwise.
099 */
100 public boolean isConnected();
101
102 /**
103 * Return the list of data types understood by the Consumer service
104 * connected to this <code>Wire</code> object. Note that subclasses of the
105 * classes in this list are acceptable data types as well.
106 *
107 * <p>
108 * The list is the value of the
109 * {@link WireConstants#WIREADMIN_CONSUMER_FLAVORS} service property of the
110 * Consumer service object connected to this object. If no such property was
111 * registered or the type of the property value is not <code>Class[]</code>,
112 * this method must return <code>null</code>.
113 *
114 * @return An array containing the list of classes understood by the
115 * Consumer service or <code>null</code> if the <code>Wire</code> is not
116 * connected, or the consumer did not register a
117 * {@link WireConstants#WIREADMIN_CONSUMER_FLAVORS} property or the
118 * value of the property is not of type <code>Class[]</code>.
119 */
120 public Class[] getFlavors();
121
122 /**
123 * Update the value.
124 *
125 * <p>
126 * This methods is called by the Producer service to notify the Consumer
127 * service connected to this <code>Wire</code> object of an updated value.
128 * <p>
129 * If the properties of this <code>Wire</code> object contain a
130 * {@link WireConstants#WIREADMIN_FILTER} property, then filtering is
131 * performed. If the Producer service connected to this <code>Wire</code>
132 * object was registered with the service property
133 * {@link WireConstants#WIREADMIN_PRODUCER_FILTERS}, the Producer service
134 * will perform the filtering according to the rules specified for the
135 * filter. Otherwise, this <code>Wire</code> object will perform the filtering
136 * of the value.
137 * <p>
138 * If no filtering is done, or the filter indicates the updated value should
139 * be delivered to the Consumer service, then this <code>Wire</code> object
140 * must call the {@link Consumer#updated} method with the updated value. If
141 * this <code>Wire</code> object is not connected, then the Consumer service
142 * must not be called and the value is ignored.
143 * <p>
144 * If the value is an <code>Envelope</code> object, and the scope name is not
145 * permitted, then the <code>Wire</code> object must ignore this call and not
146 * transfer the object to the Consumer service.
147 *
148 * <p>
149 * A <code>WireAdminEvent</code> of type {@link WireAdminEvent#WIRE_TRACE}
150 * must be broadcast by the Wire Admin service after the Consumer service
151 * has been successfully called.
152 *
153 * @param value The updated value. The value should be an instance of one of
154 * the types returned by {@link #getFlavors}.
155 * @see WireConstants#WIREADMIN_FILTER
156 */
157 public void update(Object value);
158
159 /**
160 * Poll for an updated value.
161 *
162 * <p>
163 * This methods is normally called by the Consumer service to request an
164 * updated value from the Producer service connected to this <code>Wire</code>
165 * object. This <code>Wire</code> object will call the {@link Producer#polled}
166 * method to obtain an updated value. If this <code>Wire</code> object is not
167 * connected, then the Producer service must not be called.
168 * <p>
169 *
170 * If this <code>Wire</code> object has a scope, then this method must return
171 * an array of <code>Envelope</code> objects. The objects returned must match
172 * the scope of this object. The <code>Wire</code> object must remove all
173 * <code>Envelope</code> objects with a scope name that is not in the
174 * <code>Wire</code> object's scope. Thus, the list of objects returned must
175 * only contain <code>Envelope</code> objects with a permitted scope name. If
176 * the array becomes empty, <code>null</code> must be returned.
177 *
178 * <p>
179 * A <code>WireAdminEvent</code> of type {@link WireAdminEvent#WIRE_TRACE}
180 * must be broadcast by the Wire Admin service after the Producer service
181 * has been successfully called.
182 *
183 * @return A value whose type should be one of the types returned by
184 * {@link #getFlavors},<code>Envelope[]</code>, or <code>null</code>
185 * if the <code>Wire</code> object is not connected, the Producer
186 * service threw an exception, or the Producer service returned a
187 * value which is not an instance of one of the types returned by
188 * {@link #getFlavors}.
189 */
190 public Object poll();
191
192 /**
193 * Return the last value sent through this <code>Wire</code> object.
194 *
195 * <p>
196 * The returned value is the most recent, valid value passed to the
197 * {@link #update} method or returned by the {@link #poll} method of this
198 * object. If filtering is performed by this <code>Wire</code> object, this
199 * methods returns the last value provided by the Producer service. This
200 * value may be an <code>Envelope[]</code> when the Producer service uses
201 * scoping. If the return value is an Envelope object (or array), it must be
202 * verified that the Consumer service has the proper WirePermission to see
203 * it.
204 *
205 * @return The last value passed though this <code>Wire</code> object or
206 * <code>null</code> if no valid values have been passed or the
207 * Consumer service has no permission.
208 */
209 public Object getLastValue();
210
211 /**
212 * Return the wire properties for this <code>Wire</code> object.
213 *
214 * @return The properties for this <code>Wire</code> object. The returned
215 * <code>Dictionary</code> must be read only.
216 */
217 public Dictionary getProperties();
218
219 /**
220 * Return the calculated scope of this <code>Wire</code> object.
221 *
222 * The purpose of the <code>Wire</code> object's scope is to allow a Producer
223 * and/or Consumer service to produce/consume different types over a single
224 * <code>Wire</code> object (this was deemed necessary for efficiency
225 * reasons). Both the Consumer service and the Producer service must set an
226 * array of scope names (their scope) with the service registration property
227 * <code>WIREADMIN_PRODUCER_SCOPE</code>, or
228 * <code>WIREADMIN_CONSUMER_SCOPE</code> when they can produce multiple types.
229 * If a Producer service can produce different types, it should set this
230 * property to the array of scope names it can produce, the Consumer service
231 * must set the array of scope names it can consume. The scope of a
232 * <code>Wire</code> object is defined as the intersection of permitted scope
233 * names of the Producer service and Consumer service.
234 * <p>
235 * If neither the Consumer, or the Producer service registers scope names
236 * with its service registration, then the <code>Wire</code> object's scope
237 * must be <code>null</code>.
238 * <p>
239 * The <code>Wire</code> object's scope must not change when a Producer or
240 * Consumer services modifies its scope.
241 * <p>
242 * A scope name is permitted for a Producer service when the registering
243 * bundle has <code>WirePermission[name,PRODUCE]</code>, and for a Consumer
244 * service when the registering bundle has <code>WirePermission[name,CONSUME]</code>.
245 * <p>
246 * If either Consumer service or Producer service has not set a
247 * <code>WIREADMIN_*_SCOPE</code> property, then the returned value must be
248 * <code>null</code>.
249 * <p>
250 * If the scope is set, the <code>Wire</code> object must enforce the scope
251 * names when <code>Envelope</code> objects are used as a parameter to update
252 * or returned from the <code>poll</code> method. The <code>Wire</code> object
253 * must then remove all <code>Envelope</code> objects with a scope name that
254 * is not permitted.
255 *
256 * @return A list of permitted scope names or null if the Produce or
257 * Consumer service has set no scope names.
258 */
259 public String[] getScope();
260
261 /**
262 * Return true if the given name is in this <code>Wire</code> object's scope.
263 *
264 * @param name The scope name
265 * @return true if the name is listed in the permitted scope names
266 */
267 public boolean hasScope(String name);
268 }